<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Configuration</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="The Bugzilla Guide - 3.6.4 
    Release"
HREF="index.html"><LINK
REL="UP"
TITLE="Installing Bugzilla"
HREF="installing-bugzilla.html"><LINK
REL="PREVIOUS"
TITLE="Installation"
HREF="installation.html"><LINK
REL="NEXT"
TITLE="Optional Additional Configuration"
HREF="extraconfig.html"></HEAD
><BODY
CLASS="section"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>The Bugzilla Guide - 3.6.4 
    Release</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="installation.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Chapter 2. Installing Bugzilla</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="extraconfig.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="configuration"
>2.2. Configuration</A
></H1
><DIV
CLASS="warning"
><P
></P
><TABLE
CLASS="warning"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/warning.gif"
HSPACE="5"
ALT="Warning"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13;        Poorly-configured MySQL and Bugzilla installations have
        given attackers full access to systems in the past. Please take the
        security parts of these guidelines seriously, even for Bugzilla 
        machines hidden away behind your firewall. Be certain to read
        <A
HREF="security.html"
>Chapter 4</A
> for some important security tips.
      </P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="localconfig"
>2.2.1. localconfig</A
></H2
><P
>&#13;        You should now run <TT
CLASS="filename"
>checksetup.pl</TT
> again, this time
        without the <TT
CLASS="literal"
>--check-modules</TT
> switch.
      </P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
><SAMP
CLASS="prompt"
>bash#</SAMP
> ./checksetup.pl</PRE
></FONT
></TD
></TR
></TABLE
><P
>&#13;        This time, <TT
CLASS="filename"
>checksetup.pl</TT
> should tell you that all
        the correct modules are installed and will display a message about, and
        write out a  file called, <TT
CLASS="filename"
>localconfig</TT
>. This file
        contains the default settings for a number of Bugzilla parameters.
      </P
><P
>&#13;        Load this file in your editor. The only two values you
        <EM
>need</EM
> to change are $db_driver and $db_pass,
        respectively the type of the database and the password for
        the user you will create for your database. Pick a strong
        password (for simplicity, it should not contain single quote
        characters) and put it here. $db_driver can be either 'mysql',
        'Pg' or 'oracle'.
      </P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13;          In Oracle, <TT
CLASS="literal"
>$db_name</TT
> should actually be 
          the SID name of your database (e.g. "XE" if you are using Oracle XE).
        </P
></TD
></TR
></TABLE
></DIV
><P
>&#13;        You may need to change the value of 
        <EM
>webservergroup</EM
> if your web server does not 
        run in the "apache" group.  On Debian, for example, Apache runs in 
        the "www-data" group.  If you are going to run Bugzilla on a 
        machine where you do not have root access (such as on a shared web 
        hosting account), you will need to leave
        <EM
>webservergroup</EM
> empty, ignoring the warnings 
        that <TT
CLASS="filename"
>checksetup.pl</TT
> will subsequently display 
        every time it is run.
      </P
><DIV
CLASS="caution"
><P
></P
><TABLE
CLASS="caution"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/caution.gif"
HSPACE="5"
ALT="Caution"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13;          If you are using suexec, you should use your own primary group
          for <EM
>webservergroup</EM
> rather than leaving it
          empty, and see the additional directions in the suexec section
          <A
HREF="nonroot.html#suexec"
>Section 2.6.6.1</A
>.
        </P
></TD
></TR
></TABLE
></DIV
><P
>&#13;        The other options in the <TT
CLASS="filename"
>localconfig</TT
> file
        are documented by their accompanying comments. If you have a slightly
        non-standard database setup, you may wish to change one or more of
        the other "$db_*" parameters.
      </P
></DIV
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="database-engine"
>2.2.2. Database Server</A
></H2
><P
>&#13;        This section deals with configuring your database server for use
        with Bugzilla. Currently, MySQL (<A
HREF="configuration.html#mysql"
>Section 2.2.2.2</A
>),
        PostgreSQL (<A
HREF="configuration.html#postgresql"
>Section 2.2.2.3</A
>) and Oracle (<A
HREF="configuration.html#oracle"
>Section 2.2.2.4</A
>)
        are available.
      </P
><DIV
CLASS="section"
><H3
CLASS="section"
><A
NAME="database-schema"
>2.2.2.1. Bugzilla Database Schema</A
></H3
><P
>&#13;          The Bugzilla database schema is available at
          <A
HREF="http://www.ravenbrook.com/project/p4dti/tool/cgi/bugzilla-schema/"
TARGET="_top"
>Ravenbrook</A
>.
          This very valuable tool can generate a written description of
          the Bugzilla database schema for any version of Bugzilla. It
          can also generate a diff between two versions to help someone
          see what has changed.
        </P
></DIV
><DIV
CLASS="section"
><H3
CLASS="section"
><A
NAME="mysql"
>2.2.2.2. MySQL</A
></H3
><DIV
CLASS="caution"
><P
></P
><TABLE
CLASS="caution"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/caution.gif"
HSPACE="5"
ALT="Caution"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13;            MySQL's default configuration is insecure.
            We highly recommend to run <TT
CLASS="filename"
>mysql_secure_installation</TT
>
            on Linux or the MySQL installer on Windows, and follow the instructions.
            Important points to note are:
            <P
></P
><OL
TYPE="1"
><LI
><P
>Be sure that the root account has a secure password set.</P
></LI
><LI
><P
>Do not create an anonymous account, and if it exists, say "yes"
                to remove it.</P
></LI
><LI
><P
>If your web server and MySQL server are on the same machine,
                you should disable the network access.</P
></LI
></OL
>
          </P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="section"
><H4
CLASS="section"
><A
NAME="mysql-max-allowed-packet"
>2.2.2.2.1. Allow large attachments and many comments</A
></H4
><P
>By default, MySQL will only allow you to insert things
          into the database that are smaller than 1MB. Attachments
          may be larger than this. Also, Bugzilla combines all comments
          on a single bug into one field for full-text searching, and the
          combination of all comments on a single bug could in some cases
          be larger than 1MB.</P
><P
>To change MySQL's default, you need to edit your MySQL
          configuration file, which is usually <TT
CLASS="filename"
>/etc/my.cnf</TT
>
          on Linux. We recommend that you allow at least 4MB packets by
          adding the "max_allowed_packet" parameter to your MySQL 
          configuration in the "[mysqld]" section, like this:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>[mysqld]
# Allow packets up to 4MB
max_allowed_packet=4M
          </PRE
></FONT
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="section"
><H4
CLASS="section"
><A
NAME="AEN442"
>2.2.2.2.2. Allow small words in full-text indexes</A
></H4
><P
>By default, words must be at least four characters in length
          in order to be indexed by MySQL's full-text indexes. This causes
          a lot of Bugzilla specific words to be missed, including "cc",
          "ftp" and "uri".</P
><P
>MySQL can be configured to index those words by setting the
          ft_min_word_len param to the minimum size of the words to index.
          This can be done by modifying the <TT
CLASS="filename"
>/etc/my.cnf</TT
>
          according to the example below:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>  [mysqld]
  # Allow small words in full-text indexes
  ft_min_word_len=2</PRE
></FONT
></TD
></TR
></TABLE
><P
>Rebuilding the indexes can be done based on documentation found at
          <A
HREF="http://www.mysql.com/doc/en/Fulltext_Fine-tuning.html"
TARGET="_top"
>http://www.mysql.com/doc/en/Fulltext_Fine-tuning.html</A
>.
          </P
></DIV
><DIV
CLASS="section"
><H4
CLASS="section"
><A
NAME="install-setupdatabase-adduser"
>2.2.2.2.3. Add a user to MySQL</A
></H4
><P
>&#13;            You need to add a new MySQL user for Bugzilla to use.
            (It's not safe to have Bugzilla use the MySQL root account.)
            The following instructions assume the defaults in
            <TT
CLASS="filename"
>localconfig</TT
>; if you changed those,
            you need to modify the SQL command appropriately. You will
            need the <TT
CLASS="replaceable"
><I
>$db_pass</I
></TT
> password you
            set in <TT
CLASS="filename"
>localconfig</TT
> in 
            <A
HREF="configuration.html#localconfig"
>Section 2.2.1</A
>.
          </P
><P
>&#13;            We use an SQL <B
CLASS="command"
>GRANT</B
> command to create
            a <SPAN
CLASS="QUOTE"
>"bugs"</SPAN
> user. This also restricts the 
            <SPAN
CLASS="QUOTE"
>"bugs"</SPAN
>user to operations within a database
            called <SPAN
CLASS="QUOTE"
>"bugs"</SPAN
>, and only allows the account
            to connect from <SPAN
CLASS="QUOTE"
>"localhost"</SPAN
>. Modify it to
            reflect your setup if you will be connecting from another
            machine or as a different user.
          </P
><P
>&#13;            Run the <TT
CLASS="filename"
>mysql</TT
> command-line client and enter:
          </P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;    <SAMP
CLASS="prompt"
>mysql&#62;</SAMP
> GRANT SELECT, INSERT,
           UPDATE, DELETE, INDEX, ALTER, CREATE, LOCK TABLES,
           CREATE TEMPORARY TABLES, DROP, REFERENCES ON bugs.*
           TO bugs@localhost IDENTIFIED BY '<TT
CLASS="replaceable"
><I
>$db_pass</I
></TT
>';
    <SAMP
CLASS="prompt"
>mysql&#62;</SAMP
> FLUSH PRIVILEGES;
          </PRE
></FONT
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="section"
><H4
CLASS="section"
><A
NAME="AEN469"
>2.2.2.2.4. Permit attachments table to grow beyond 4GB</A
></H4
><P
>&#13;            By default, MySQL will limit the size of a table to 4GB.
            This limit is present even if the underlying filesystem
            has no such limit.  To set a higher limit, follow these
            instructions.
          </P
><P
>&#13;            After you have completed the rest of the installation (or at least the
            database setup parts), you should run the <TT
CLASS="filename"
>MySQL</TT
>
            command-line client and enter the following, replacing <TT
CLASS="literal"
>$bugs_db</TT
>
            with your Bugzilla database name (<EM
>bugs</EM
> by default):
          </P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;    <SAMP
CLASS="prompt"
>mysql&#62;</SAMP
> use <TT
CLASS="replaceable"
><I
>$bugs_db</I
></TT
>
    <SAMP
CLASS="prompt"
>mysql&#62;</SAMP
> ALTER TABLE attachments
           AVG_ROW_LENGTH=1000000, MAX_ROWS=20000;
          </PRE
></FONT
></TD
></TR
></TABLE
><P
>&#13;            The above command will change the limit to 20GB. Mysql will have 
            to make a temporary copy of your entire table to do this. Ideally, 
            you should do this when your attachments table is still small. 
          </P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13;              This does not affect Big Files, attachments that are stored directly
              on disk instead of in the database.
            </P
></TD
></TR
></TABLE
></DIV
></DIV
></DIV
><DIV
CLASS="section"
><H3
CLASS="section"
><A
NAME="postgresql"
>2.2.2.3. PostgreSQL</A
></H3
><DIV
CLASS="section"
><H4
CLASS="section"
><A
NAME="AEN485"
>2.2.2.3.1. Add a User to PostgreSQL</A
></H4
><P
>You need to add a new user to PostgreSQL for the Bugzilla
          application to use when accessing the database. The following instructions
          assume the defaults in <TT
CLASS="filename"
>localconfig</TT
>; if you
          changed those, you need to modify the commands appropriately. You will
          need the <TT
CLASS="replaceable"
><I
>$db_pass</I
></TT
> password you
          set in <TT
CLASS="filename"
>localconfig</TT
> in 
          <A
HREF="configuration.html#localconfig"
>Section 2.2.1</A
>.</P
><P
>On most systems, to create the user in PostgreSQL, you will need to
          login as the root user, and then</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
> <SAMP
CLASS="prompt"
>bash#</SAMP
> su - postgres</PRE
></FONT
></TD
></TR
></TABLE
><P
>As the postgres user, you then need to create a new user: </P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
> <SAMP
CLASS="prompt"
>bash$</SAMP
> createuser -U postgres -dRSP bugs</PRE
></FONT
></TD
></TR
></TABLE
><P
>When asked for a password, provide the password which will be set as
          <TT
CLASS="replaceable"
><I
>$db_pass</I
></TT
> in <TT
CLASS="filename"
>localconfig</TT
>.
          The created user will not be a superuser (-S) and will not be able to create
          new users (-R). He will only have the ability to create databases (-d).</P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>If your are running PostgreSQL 8.0, you must replace -dRSP by -dAP.</P
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="section"
><H4
CLASS="section"
><A
NAME="AEN503"
>2.2.2.3.2. Configure PostgreSQL</A
></H4
><P
>Now, you will need to edit <TT
CLASS="filename"
>pg_hba.conf</TT
> which is
          usually located in <TT
CLASS="filename"
>/var/lib/pgsql/data/</TT
>. In this file,
          you will need to add a new line to it as follows:</P
><P
>&#13;            <SAMP
CLASS="computeroutput"
>host   all    bugs   127.0.0.1    255.255.255.255  md5</SAMP
>
          </P
><P
>This means that for TCP/IP (host) connections, allow connections from
          '127.0.0.1' to 'all' databases on this server from the 'bugs' user, and use
          password authentication (md5) for that user.</P
><P
>Now, you will need to restart PostgreSQL, but you will need to fully
          stop and start the server rather than just restarting due to the possibility
          of a change to <TT
CLASS="filename"
>postgresql.conf</TT
>. After the server has
          restarted, you will need to edit <TT
CLASS="filename"
>localconfig</TT
>, finding
          the <TT
CLASS="literal"
>$db_driver</TT
> variable and setting it to
          <TT
CLASS="literal"
>Pg</TT
> and changing the password in <TT
CLASS="literal"
>$db_pass</TT
>
          to the one you picked previously, while setting up the account.</P
></DIV
></DIV
><DIV
CLASS="section"
><H3
CLASS="section"
><A
NAME="oracle"
>2.2.2.4. Oracle</A
></H3
><DIV
CLASS="section"
><H4
CLASS="section"
><A
NAME="AEN519"
>2.2.2.4.1. Create a New Tablespace</A
></H4
><P
>&#13;            You can use the existing tablespace or create a new one for Bugzilla.
            To create a new tablespace, run the following command:
          </P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;    CREATE TABLESPACE bugs
    DATAFILE '<TT
CLASS="replaceable"
><I
>$path_to_datafile</I
></TT
>' SIZE 500M
    AUTOEXTEND ON NEXT 30M MAXSIZE UNLIMITED
          </PRE
></FONT
></TD
></TR
></TABLE
><P
>&#13;            Here, the name of the tablespace is 'bugs', but you can
            choose another name. <TT
CLASS="replaceable"
><I
>$path_to_datafile</I
></TT
> is
            the path to the file containing your database, for instance
            <TT
CLASS="filename"
>/u01/oradata/bugzilla.dbf</TT
>.
            The initial size of the database file is set in this example to 500 Mb,
            with an increment of 30 Mb everytime we reach the size limit of the file.
          </P
></DIV
><DIV
CLASS="section"
><H4
CLASS="section"
><A
NAME="AEN527"
>2.2.2.4.2. Add a User to Oracle</A
></H4
><P
>&#13;            The user name and password must match what you set in
            <TT
CLASS="filename"
>localconfig</TT
> (<TT
CLASS="literal"
>$db_user</TT
>
            and <TT
CLASS="literal"
>$db_pass</TT
>, respectively). Here, we assume that
            the user name is 'bugs' and the tablespace name is the same
            as above. 
          </P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;    CREATE USER bugs
    IDENTIFIED BY "<TT
CLASS="replaceable"
><I
>$db_pass</I
></TT
>"
    DEFAULT TABLESPACE bugs
    TEMPORARY TABLESPACE TEMP
    PROFILE DEFAULT;
    -- GRANT/REVOKE ROLE PRIVILEGES
    GRANT CONNECT TO bugs;
    GRANT RESOURCE TO bugs;
    -- GRANT/REVOKE SYSTEM PRIVILEGES
    GRANT UNLIMITED TABLESPACE TO bugs;
    GRANT EXECUTE ON CTXSYS.CTX_DDL TO bugs;
          </PRE
></FONT
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="section"
><H4
CLASS="section"
><A
NAME="AEN535"
>2.2.2.4.3. Configure the Web Server</A
></H4
><P
>&#13;            If you use Apache, append these lines to <TT
CLASS="filename"
>httpd.conf</TT
>
            to set ORACLE_HOME and LD_LIBRARY_PATH. For instance:
          </P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;    SetEnv ORACLE_HOME /u01/app/oracle/product/10.2.0/
    SetEnv LD_LIBRARY_PATH /u01/app/oracle/product/10.2.0/lib/
          </PRE
></FONT
></TD
></TR
></TABLE
><P
>&#13;            When this is done, restart your web server.
          </P
></DIV
></DIV
></DIV
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="AEN541"
>2.2.3. checksetup.pl</A
></H2
><P
>&#13;        Next, rerun <TT
CLASS="filename"
>checksetup.pl</TT
>. It reconfirms
        that all the modules are present, and notices the altered 
        localconfig file, which it assumes you have edited to your
        satisfaction. It compiles the UI templates,
        connects to the database using the 'bugs'
        user you created and the password you defined, and creates the 
        'bugs' database and the tables therein. 
      </P
><P
>&#13;        After that, it asks for details of an administrator account. Bugzilla
        can have multiple administrators - you can create more later - but
        it needs one to start off with.
        Enter the email address of an administrator, his or her full name, 
        and a suitable Bugzilla password.
      </P
><P
>&#13;        <TT
CLASS="filename"
>checksetup.pl</TT
> will then finish. You may rerun
        <TT
CLASS="filename"
>checksetup.pl</TT
> at any time if you wish.
      </P
></DIV
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="http"
>2.2.4. Web server</A
></H2
><P
>&#13;        Configure your web server according to the instructions in the
        appropriate section. (If it makes a difference in your choice,
        the Bugzilla Team recommends Apache.) To check whether your web server
	is correctly configured, try to access <TT
CLASS="filename"
>testagent.cgi</TT
>
	from your web server. If "OK" is displayed, then your configuration
	is successful. Regardless of which web server
        you are using, however, ensure that sensitive information is
        not remotely available by properly applying the access controls in
        <A
HREF="security-webserver.html#security-webserver-access"
>Section 4.2.1</A
>. You can run
        <TT
CLASS="filename"
>testserver.pl</TT
> to check if your web server serves
        Bugzilla files as expected.
      </P
><DIV
CLASS="section"
><H3
CLASS="section"
><A
NAME="http-apache"
>2.2.4.1. Bugzilla using Apache</A
></H3
><P
>You have two options for running Bugzilla under Apache - 
          <A
HREF="configuration.html#http-apache-mod_cgi"
>mod_cgi</A
> (the default) and
          <A
HREF="configuration.html#http-apache-mod_perl"
>mod_perl</A
> (new in Bugzilla
          2.23)
        </P
><DIV
CLASS="section"
><H4
CLASS="section"
><A
NAME="http-apache-mod_cgi"
>2.2.4.1.1. Apache <SPAN
CLASS="productname"
>httpd</SPAN
> with mod_cgi</A
></H4
><P
>&#13;            To configure your Apache web server to work with Bugzilla while using
            mod_cgi, do the following:
            </P
><DIV
CLASS="procedure"
><OL
TYPE="1"
><LI
CLASS="step"
><P
>&#13;                Load <TT
CLASS="filename"
>httpd.conf</TT
> in your editor.
                In Fedora and Red Hat Linux, this file is found in
                <TT
CLASS="filename"
>/etc/httpd/conf</TT
>.
                </P
></LI
><LI
CLASS="step"
><P
>&#13;                Apache uses <SAMP
CLASS="computeroutput"
>&#60;Directory&#62;</SAMP
>
                directives to permit fine-grained permission setting. Add the
                following lines to a directive that applies to the location
                of your Bugzilla installation. (If such a section does not
                exist, you'll want to add one.) In this example, Bugzilla has
                been installed at 
                <TT
CLASS="filename"
>/var/www/html/bugzilla</TT
>.
                </P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;    &#60;Directory /var/www/html/bugzilla&#62;
    AddHandler cgi-script .cgi
    Options +Indexes +ExecCGI
    DirectoryIndex index.cgi
    AllowOverride Limit
    &#60;/Directory&#62;
                </PRE
></FONT
></TD
></TR
></TABLE
><P
>&#13;                These instructions: allow apache to run .cgi files found
                within the bugzilla directory; instructs the server to look
                for a file called <TT
CLASS="filename"
>index.cgi</TT
> if someone
                only types the directory name into the browser; and allows
                Bugzilla's <TT
CLASS="filename"
>.htaccess</TT
> files to override
                global permissions.
                </P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13;                    It is possible to make these changes globally, or to the
                    directive controlling Bugzilla's parent directory (e.g.
                    <SAMP
CLASS="computeroutput"
>&#60;Directory /var/www/html/&#62;</SAMP
>).
                    Such changes would also apply to the Bugzilla directory...
                    but they would also apply to many other places where they
                    may or may not be appropriate. In most cases, including
                    this one, it is better to be as restrictive as possible
                    when granting extra access.
                </P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13;                    On Windows, you may have to also add the
                    <SAMP
CLASS="computeroutput"
>ScriptInterpreterSource Registry-Strict</SAMP
>
                    line, see <A
HREF="os-specific.html#win32-http"
>Windows specific notes</A
>.
                </P
></TD
></TR
></TABLE
></DIV
></LI
><LI
CLASS="step"
><P
>&#13;                <TT
CLASS="filename"
>checksetup.pl</TT
> can set tighter permissions
                on Bugzilla's files and directories if it knows what group the
                web server runs as. Find the <SAMP
CLASS="computeroutput"
>Group</SAMP
>
                line in <TT
CLASS="filename"
>httpd.conf</TT
>, place the value found
                there in the <TT
CLASS="replaceable"
><I
>$webservergroup</I
></TT
> variable
                in <TT
CLASS="filename"
>localconfig</TT
>, then rerun
                <TT
CLASS="filename"
>checksetup.pl</TT
>.
                </P
></LI
><LI
CLASS="step"
><P
>&#13;                Optional: If Bugzilla does not actually reside in the webspace
                directory, but instead has been symbolically linked there, you
                will need to add the following to the
                <SAMP
CLASS="computeroutput"
>Options</SAMP
> line of the Bugzilla 
                <SAMP
CLASS="computeroutput"
>&#60;Directory&#62;</SAMP
> directive
                (the same one as in the step above):
                </P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;    +FollowSymLinks
                </PRE
></FONT
></TD
></TR
></TABLE
><P
>&#13;                Without this directive, Apache will not follow symbolic links
                to places outside its own directory structure, and you will be
                unable to run Bugzilla.
                </P
></LI
></OL
></DIV
></DIV
><DIV
CLASS="section"
><H4
CLASS="section"
><A
NAME="http-apache-mod_perl"
>2.2.4.1.2. Apache <SPAN
CLASS="productname"
>httpd</SPAN
> with mod_perl</A
></H4
><P
>Some configuration is required to make Bugzilla work with Apache
            and mod_perl</P
><DIV
CLASS="procedure"
><OL
TYPE="1"
><LI
CLASS="step"
><P
>&#13;                Load <TT
CLASS="filename"
>httpd.conf</TT
> in your editor.
                In Fedora and Red Hat Linux, this file is found in
                <TT
CLASS="filename"
>/etc/httpd/conf</TT
>.
                </P
></LI
><LI
CLASS="step"
><P
>Add the following information to your httpd.conf file, substituting
                where appropriate with your own local paths.</P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>This should be used instead of the &#60;Directory&#62; block
                shown above. This should also be above any other <TT
CLASS="literal"
>mod_perl</TT
>
                directives within the <TT
CLASS="filename"
>httpd.conf</TT
> and must be specified
                in the order as below.</P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="warning"
><P
></P
><TABLE
CLASS="warning"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/warning.gif"
HSPACE="5"
ALT="Warning"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>You should also ensure that you have disabled <TT
CLASS="literal"
>KeepAlive</TT
>
                support in your Apache install when utilizing Bugzilla under mod_perl</P
></TD
></TR
></TABLE
></DIV
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;    PerlSwitches -I/var/www/html/bugzilla -I/var/www/html/bugzilla/lib -w -T
    PerlConfigRequire /var/www/html/bugzilla/mod_perl.pl
                </PRE
></FONT
></TD
></TR
></TABLE
></LI
><LI
CLASS="step"
><P
>&#13;					<TT
CLASS="filename"
>checksetup.pl</TT
> can set tighter permissions
					on Bugzilla's files and directories if it knows what group the
					web server runs as. Find the <SAMP
CLASS="computeroutput"
>Group</SAMP
>
					line in <TT
CLASS="filename"
>httpd.conf</TT
>, place the value found
					there in the <TT
CLASS="replaceable"
><I
>$webservergroup</I
></TT
> variable
					in <TT
CLASS="filename"
>localconfig</TT
>, then rerun
					<TT
CLASS="filename"
>checksetup.pl</TT
>.
				</P
></LI
></OL
></DIV
><P
>On restarting Apache, Bugzilla should now be running within the
            mod_perl environment. Please ensure you have run checksetup.pl to set
		    permissions before you restart Apache.</P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>Please bear the following points in mind when looking at using 
                Bugzilla under mod_perl: 
            <P
></P
><UL
><LI
><P
>&#13;                    mod_perl support in Bugzilla can take up a HUGE amount of RAM. You could be
                    looking at 30MB per httpd child, easily. Basically, you just need a lot of RAM.
                    The more RAM you can get, the better. mod_perl is basically trading RAM for
                    speed. At least 2GB total system RAM is recommended for running Bugzilla under
                    mod_perl.
                </P
></LI
><LI
><P
>&#13;                    Under mod_perl, you have to restart Apache if you make any manual change to
                    any Bugzilla file. You can't just reload--you have to actually 
					<EM
>restart</EM
> the server (as in make sure it stops and starts 
					again). You <EM
>can</EM
> change localconfig and the params file 
					manually, if you want, because those are re-read every time you load a page.
                </P
></LI
><LI
><P
>&#13;                    You must run in Apache's Prefork MPM (this is the default). The Worker MPM
                    may not work--we haven't tested Bugzilla's mod_perl support under threads.
					(And, in fact, we're fairly sure it <EM
>won't</EM
> work.)
                </P
></LI
><LI
><P
>&#13;                    Bugzilla generally expects to be the only mod_perl application running on
                    your entire server. It may or may not work if there are other applications also
                    running under mod_perl. It does try its best to play nice with other mod_perl
                    applications, but it still may have conflicts.
                </P
></LI
><LI
><P
>&#13;                    It is recommended that you have one Bugzilla instance running under mod_perl
                    on your server. Bugzilla has not been tested with more than one instance running.
                </P
></LI
></UL
>
            </P
></TD
></TR
></TABLE
></DIV
></DIV
></DIV
><DIV
CLASS="section"
><H3
CLASS="section"
><A
NAME="http-iis"
>2.2.4.2. Microsoft <SPAN
CLASS="productname"
>Internet Information Services</SPAN
></A
></H3
><P
>&#13;          If you are running Bugzilla on Windows and choose to use
          Microsoft's <SPAN
CLASS="productname"
>Internet Information Services</SPAN
>
          or <SPAN
CLASS="productname"
>Personal Web Server</SPAN
> you will need
          to perform a number of other configuration steps as explained below.
          You may also want to refer to the following Microsoft Knowledge
          Base articles: 
          <A
HREF="http://support.microsoft.com/default.aspx?scid=kb;en-us;245225"
TARGET="_top"
>245225</A
> 
          <SPAN
CLASS="QUOTE"
>"HOW TO: Configure and Test a PERL Script with IIS 4.0,
          5.0, and 5.1"</SPAN
> (for <SPAN
CLASS="productname"
>Internet Information
          Services</SPAN
>) and 
          <A
HREF="http://support.microsoft.com/default.aspx?scid=kb;en-us;231998"
TARGET="_top"
>231998</A
>          
          <SPAN
CLASS="QUOTE"
>"HOW TO: FP2000: How to Use Perl with Microsoft Personal Web
          Server on Windows 95/98"</SPAN
> (for <SPAN
CLASS="productname"
>Personal Web
          Server</SPAN
>).
        </P
><P
>&#13;          You will need to create a virtual directory for the Bugzilla
          install.  Put the Bugzilla files in a directory that is named
          something <EM
>other</EM
> than what you want your
          end-users accessing.  That is, if you want your users to access
          your Bugzilla installation through 
          <SPAN
CLASS="QUOTE"
>"http://&#60;yourdomainname&#62;/Bugzilla"</SPAN
>, then do
          <EM
>not</EM
> put your Bugzilla files in a directory
          named <SPAN
CLASS="QUOTE"
>"Bugzilla"</SPAN
>.  Instead, place them in a different
          location, and then use the IIS Administration tool to create a
          Virtual Directory named "Bugzilla" that acts as an alias for the
          actual location of the files.  When creating that virtual directory,
          make sure you add the <SPAN
CLASS="QUOTE"
>"Execute (such as ISAPI applications or
          CGI)"</SPAN
> access permission.
        </P
><P
>&#13;          You will also need to tell IIS how to handle Bugzilla's
          .cgi files. Using the IIS Administration tool again, open up
          the properties for the new virtual directory and select the
          Configuration option to access the Script Mappings. Create an
          entry mapping .cgi to:
        </P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;&#60;full path to perl.exe &#62;\perl.exe -x&#60;full path to Bugzilla&#62; -wT "%s" %s
        </PRE
></FONT
></TD
></TR
></TABLE
><P
>&#13;          For example:
        </P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s
        </PRE
></FONT
></TD
></TR
></TABLE
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13;            The ActiveState install may have already created an entry for
            .pl files that is limited to <SPAN
CLASS="QUOTE"
>"GET,HEAD,POST"</SPAN
>. If
            so, this mapping should be <EM
>removed</EM
> as
            Bugzilla's .pl files are not designed to be run via a web server.
          </P
></TD
></TR
></TABLE
></DIV
><P
>&#13;          IIS will also need to know that the index.cgi should be treated
          as a default document.  On the Documents tab page of the virtual
          directory properties, you need to add index.cgi as a default
          document type.  If you  wish, you may remove the other default
          document types for this particular virtual directory, since Bugzilla 
          doesn't use any of them.
        </P
><P
>&#13;          Also, and this can't be stressed enough, make sure that files
          such as <TT
CLASS="filename"
>localconfig</TT
> and your
          <TT
CLASS="filename"
>data</TT
> directory are
          secured as described in <A
HREF="security-webserver.html#security-webserver-access"
>Section 4.2.1</A
>.
        </P
></DIV
></DIV
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="install-config-bugzilla"
>2.2.5. Bugzilla</A
></H2
><P
>&#13;        Your Bugzilla should now be working. Access 
        <TT
CLASS="filename"
>http://&#60;your-bugzilla-server&#62;/</TT
> - 
        you should see the Bugzilla
        front page. If not, consult the Troubleshooting section,
        <A
HREF="troubleshooting.html"
>Appendix A</A
>.
      </P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13;          The URL above may be incorrect if you installed Bugzilla into a 
          subdirectory or used a symbolic link from your web site root to 
          the Bugzilla directory.
        </P
></TD
></TR
></TABLE
></DIV
><P
>&#13;        Log in with the administrator account you defined in the last 
        <TT
CLASS="filename"
>checksetup.pl</TT
> run. You should go through 
        the Parameters page and see if there are any you wish to change.
        They key parameters are documented in <A
HREF="parameters.html"
>Section 3.1</A
>;
        you should certainly alter 
        <B
CLASS="command"
>maintainer</B
> and <B
CLASS="command"
>urlbase</B
>; 
        you may also want to alter 
        <B
CLASS="command"
>cookiepath</B
> or <B
CLASS="command"
>requirelogin</B
>.
      </P
><P
>&#13;        Bugzilla has several optional features which require extra 
        configuration. You can read about those in
        <A
HREF="extraconfig.html"
>Section 2.3</A
>.
      </P
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="installation.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="extraconfig.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Installation</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="installing-bugzilla.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Optional Additional Configuration</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>